/*!
 * \file IUftStraCtx.h
 * \project	WonderTrader
 *
 * \author Wesley
 * \date 2020/03/30
 * 
 * \brief UFT策略上下文接口定义
 * 
 * \details 该文件定义了UFT（Ultra Frequency Trading）策略的核心接口。
 *          UFT策略是一种极高频交易策略，主要特点包括：
 *          - 微秒级的交易执行速度
 *          - 依赖最精细的市场数据（逐笔成交、委托队列等）
 *          - 支持复杂的订单类型（FAK、FOK等）
 *          - 适用于延迟敏感的套利策略
 *          该接口提供了超高频交易所需的全部功能，包括：
 *          - 极高精度行情数据处理
 *          - 多种高速下单方式
 *          - 实时持仓和风险管理
 *          - 低延迟数据获取接口
 */
#pragma once
#include <stdint.h>
#include <string>
#include "ExecuteDefs.h"

#include "../Includes/WTSMarcos.h"

NS_WTP_BEGIN
class WTSCommodityInfo;
class WTSTickSlice;
class WTSKlineSlice;
class WTSTickData;
struct WTSBarStruct;

/*!
 * \brief 下单标志定义
 * 
 * \details 定义了UFT策略中支持的各种下单类型标志：
 */

/*!
 * \brief 普通订单标志
 * \details 标准的限价或市价订单，会一直挂在盘口直到成交或撤销
 */
static const int UFT_OrderFlag_Nor = 0;

/*!
 * \brief FAK订单标志（Fill And Kill）
 * \details 立即成交剩余撤销订单，能成交多少就成交多少，剩余部分立即撤销
 */
static const int UFT_OrderFlag_FAK = 1;

/*!
 * \brief FOK订单标志（Fill Or Kill）
 * \details 立即全部成交或全部撤销订单，要么全部成交，要么全部撤销
 */
static const int UFT_OrderFlag_FOK = 2;

/*!
 * \class IUftStraCtx
 * \brief UFT策略上下文接口
 * 
 * \details 这是UFT（Ultra Frequency Trading）策略的核心接口，定义了超高频交易所需的全部功能：
 * 
 * **主要功能模块：**
 * - **极速数据接收**: 微秒级Tick数据、委托队列、委托明细、成交数据等
 * - **高速交易接口**: 支持多种订单类型的极速下单
 * - **订单管理**: 快速下单、撤单、批量撤单等
 * - **持仓管理**: 实时持仓查询、盈亏计算、风险控制
 * - **数据订阅**: 超低延迟的数据订阅机制
 * - **辅助功能**: 高性能日志和状态管理
 * 
 * **适用策略类型：**
 * - 极高频套利策略
 * - 微秒级对冲策略
 * - 跨市场套利
 * - 网格交易策略
 * - 事件驱动策略
 * - 延迟套利策略
 * 
 * **技术特点：**
 * - 支持微秒级交易执行
 * - 提供最精细的市场数据
 * - 支持复杂的订单组合
 * - 极低延迟的风险控制
 * - 超高精度时间戳支持
 * 
 * \note 该接口为纯虚接口，具体实现由UftStraContext类提供
 * \warning UFT策略对延迟极其敏感，所有操作都必须优化到极致
 * \see UftStraContext, UftStraBaseCtx
 */
class IUftStraCtx
{
public:
	/*!
	 * \brief 构造函数
	 * \param[in] name 策略名称
	 */
	IUftStraCtx(const char* name) :_name(name) {}
	virtual ~IUftStraCtx() {}

	/*!
	 * \brief 获取策略名称
	 * \return 策略名称字符串
	 */
	const char* name() const { return _name.c_str(); }

public:
	/*!
	 * \brief 获取策略ID
	 * \return 策略的唯一标识ID
	 */
	virtual uint32_t id() = 0;

	//回调函数
	/*!
	 * \brief 策略初始化回调
	 * 
	 * \details 策略启动时被调用，用于进行策略的初始化工作：
	 *          - 加载策略参数和配置
	 *          - 初始化极高频数据结构
	 *          - 订阅需要的超高频数据
	 *          - 设置延迟优化参数
	 * 
	 * \note UFT策略的初始化需要特别注意内存和CPU优化
	 * \warning 不要在此函数中进行任何可能影响性能的操作
	 */
	virtual void on_init() = 0;
	
	/*!
	 * \brief Tick数据回调
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] newTick 最新的Tick数据
	 * 
	 * \details 每当有新的Tick数据到达时被调用，这是UFT策略最重要的数据源：
	 *          - 包含最新的买卖价格和数量
	 *          - 包含微秒级时间戳
	 *          - 提供成交量和成交额信息
	 *          - 是大多数UFT策略的核心信号来源
	 * 
	 * \note 该回调调用频率极高，必须优化到极致
	 * \warning 任何复杂计算都可能影响策略性能
	 */
	virtual void on_tick(const char* stdCode, WTSTickData* newTick) = 0;
	
	/*!
	 * \brief 委托队列数据回调
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] newOrdQue 最新的委托队列数据
	 * 
	 * \details 每当有新的委托队列数据时被调用：
	 *          - 提供买卖盘口的详细委托信息
	 *          - 用于分析市场深度和流动性
	 *          - 适用于基于盘口的极高频策略
	 *          - 可以预测短期价格变动
	 * 
	 * \note 委托队列数据更新频率极高，处理必须非常高效
	 */
	virtual void on_order_queue(const char* stdCode, WTSOrdQueData* newOrdQue) = 0;
	
	/*!
	 * \brief 委托明细数据回调
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] newOrdDtl 最新的委托明细数据
	 * 
	 * \details 每当有新的委托明细数据时被调用：
	 *          - 提供每笔委托的详细信息
	 *          - 包含委托价格、数量、方向等
	 *          - 用于极精细的市场微观结构分析
	 *          - 可以识别大单和异常交易行为
	 */
	virtual void on_order_detail(const char* stdCode, WTSOrdDtlData* newOrdDtl) = 0;
	
	/*!
	 * \brief 逐笔成交数据回调
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] newTrans 最新的成交数据
	 * 
	 * \details 每当有新的逐笔成交数据时被调用：
	 *          - 提供每笔成交的详细信息
	 *          - 包含成交价格、数量、方向等
	 *          - 用于分析实际成交情况和资金流向
	 *          - 可以识别市场冲击和价格发现过程
	 */
	virtual void on_transaction(const char* stdCode, WTSTransData* newTrans) = 0;
	
	/*!
	 * \brief K线数据更新回调
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] period 周期类型字符串
	 * \param[in] times 周期倍数
	 * \param[in] newBar 最新的K线数据
	 * 
	 * \details K线数据更新时被调用，对于UFT策略可选使用：
	 *          - 通常UFT策略更关注微秒级数据
	 *          - 可用于长期趋势确认或风险控制
	 * 
	 * \note 默认为空实现，策略可根据需要重写
	 */
	virtual void on_bar(const char* stdCode, const char* period, uint32_t times, WTSBarStruct* newBar) {}
	
	/*!
	 * \brief 交易时段开始回调
	 * \param[in] uTDate 交易日期，格式为YYYYMMDD
	 * 
	 * \details 交易时段开始时被调用：
	 *          - 可用于重置日内状态
	 *          - 进行开盘前的准备工作
	 * 
	 * \note 默认为空实现，策略可根据需要重写
	 */
	virtual void on_session_begin(uint32_t uTDate) {}
	
	/*!
	 * \brief 交易时段结束回调
	 * \param[in] uTDate 交易日期，格式为YYYYMMDD
	 * 
	 * \details 交易时段结束时被调用：
	 *          - 可用于收盘后的清理工作
	 *          - 保存交易统计数据
	 * 
	 * \note 默认为空实现，策略可根据需要重写
	 */
	virtual void on_session_end(uint32_t uTDate) {}

	/*!
	 * \brief 回测结束回调
	 * 
	 * \details 仅在历史回测模式下，回测结束时被调用：
	 *          - 计算和输出回测统计结果
	 *          - 保存回测报告
	 * 
	 * \note 该函数只在回测模式下才会被调用
	 */
	virtual void	on_bactest_end() {};

	/*!
	 * \brief Tick数据更新后回调
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] newTick 最新的Tick数据
	 * 
	 * \details Tick数据处理完成后的回调：
	 *          - 可用于获取处理后的数据
	 *          - 进行后续的数据分析
	 * 
	 * \note 默认为空实现，策略可根据需要重写
	 */
	virtual void	on_tick_updated(const char* stdCode, WTSTickData* newTick) {}
	
	/*!
	 * \brief 委托队列更新后回调
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] newOrdQue 最新的委托队列数据
	 * 
	 * \note 默认为空实现，策略可根据需要重写
	 */
	virtual void	on_ordque_updated(const char* stdCode, WTSOrdQueData* newOrdQue) {}
	
	/*!
	 * \brief 委托明细更新后回调
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] newOrdDtl 最新的委托明细数据
	 * 
	 * \note 默认为空实现，策略可根据需要重写
	 */
	virtual void	on_orddtl_updated(const char* stdCode, WTSOrdDtlData* newOrdDtl) {}
	
	/*!
	 * \brief 成交数据更新后回调
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] newTrans 最新的成交数据
	 * 
	 * \note 默认为空实现，策略可根据需要重写
	 */
	virtual void	on_trans_updated(const char* stdCode, WTSTransData* newTrans) {}

	//交易接口

	/*!
	 * \brief 获取当前日期
	 * \return 当前日期，格式为YYYYMMDD
	 */
	virtual uint32_t	stra_get_date() = 0;
	
	/*!
	 * \brief 获取当前时间
	 * \return 当前时间，格式为HHMM
	 */
	virtual uint32_t	stra_get_time() = 0;
	
	/*!
	 * \brief 获取当前秒数
	 * \return 当前时间的秒数部分
	 * 
	 * \details 提供更高精度的时间信息，适用于超高频交易的精确计时需求
	 */
	virtual uint32_t	stra_get_secs() = 0;

	/*!
	 * \brief 撤销指定订单
	 * \param[in] localid 本地订单ID
	 * \return 是否成功提交撤单请求
	 * 
	 * \details 根据本地订单ID撤销特定订单：
	 *          - localid是下单时返回的本地订单号
	 *          - 撤单是异步操作，需要通过回调确认结果
	 *          - UFT策略中撤单速度至关重要
	 */
	virtual bool		stra_cancel(uint32_t localid) = 0;
	
	/*!
	 * \brief 批量撤销订单
	 * \param[in] stdCode 标准化合约代码
	 * \return 被撤销的订单ID列表
	 * 
	 * \details 撤销指定合约的所有订单：
	 *          - 一键撤销所有未成交订单
	 *          - 用于紧急风险控制
	 *          - 返回实际被撤销的订单列表
	 */
	virtual OrderIDs	stra_cancel_all(const char* stdCode) = 0;

	/*!
	 * \brief 买入下单接口
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] price 下单价格，0表示市价单
	 * \param[in] qty 下单数量
	 * \param[in] flag 下单标志: 0-普通单，1-FAK，2-FOK，默认为0
	 * \return 本地订单ID列表
	 * 
	 * \details 提交买入订单：
	 *          - price=0: 市价单，以最优对手价成交
	 *          - price>0: 限价单，按指定价格成交
	 *          - flag控制订单执行方式，UFT策略通常使用FAK或FOK
	 * 
	 * \note 该操作是异步的，执行结果需要通过回调确认
	 * \warning UFT策略中要特别注意下单延迟和滑点控制
	 */
	virtual OrderIDs	stra_buy(const char* stdCode, double price, double qty, int flag = 0) { return OrderIDs(); }

	/*!
	 * \brief 卖出下单接口
	 * \param[in] stdCode 标准化合约代码
	 * \param[in] price 下单价格，0表示市价单
	 * \param[in] qty 下单数量
	 * \param[in] flag 下单标志: 0-普通单，1-FAK，2-FOK，默认为0
	 * \return 本地订单ID列表
	 * 
	 * \details 提交卖出订单，参数含义同stra_buy
	 * 
	 * \note 该操作是异步的，执行结果需要通过回调确认
	 */
	virtual OrderIDs	stra_sell(const char* stdCode, double price, double qty, int flag = 0) { return OrderIDs(); }

	/*!
	 * \brief 开多仓接口
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] price 委托价格
	 * \param[in] qty 下单数量
	 * \param[in] flag 下单标志: 0-普通单，1-FAK，2-FOK，默认为0
	 * \return 本地订单ID
	 * 
	 * \details 开立多头仓位的便捷接口：
	 *          - 适用于期货等有方向性的品种
	 *          - 自动处理开仓逻辑
	 * 
	 * \note 默认返回0，子类可重写实现具体逻辑
	 */
	virtual uint32_t	stra_enter_long(const char* stdCode, double price, double qty, int flag = 0) { return 0; }

	/*!
	 * \brief 开空仓接口
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] price 委托价格
	 * \param[in] qty 下单数量
	 * \param[in] flag 下单标志: 0-普通单，1-FAK，2-FOK，默认为0
	 * \return 本地订单ID
	 * 
	 * \details 开立空头仓位的便捷接口
	 * 
	 * \note 默认返回0，子类可重写实现具体逻辑
	 */
	virtual uint32_t	stra_enter_short(const char* stdCode, double price, double qty, int flag = 0) { return 0; }

	/*!
	 * \brief 平多仓接口
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] price 委托价格
	 * \param[in] qty 下单数量
	 * \param[in] isToday 是否为今仓，SHFE和INE专用
	 * \param[in] flag 下单标志: 0-普通单，1-FAK，2-FOK，默认为0
	 * \return 本地订单ID
	 * 
	 * \details 平掉多头仓位的便捷接口：
	 *          - isToday用于区分今仓和昨仓（上期所特有）
	 *          - 自动处理平仓逻辑
	 * 
	 * \note 默认返回0，子类可重写实现具体逻辑
	 */
	virtual uint32_t	stra_exit_long(const char* stdCode, double price, double qty, bool isToday = false, int flag = 0) { return 0; }

	/*!
	 * \brief 平空仓接口
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] price 委托价格
	 * \param[in] qty 下单数量
	 * \param[in] isToday 是否为今仓，SHFE和INE专用
	 * \param[in] flag 下单标志: 0-普通单，1-FAK，2-FOK，默认为0
	 * \return 本地订单ID
	 * 
	 * \details 平掉空头仓位的便捷接口
	 * 
	 * \note 默认返回0，子类可重写实现具体逻辑
	 */
	virtual uint32_t	stra_exit_short(const char* stdCode, double price, double qty, bool isToday = false, int flag = 0) { return 0; }

	/*!
	 * \brief 获取品种信息
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \return 品种信息对象指针
	 */
	virtual WTSCommodityInfo* stra_get_comminfo(const char* stdCode) = 0;

	/*!
	 * \brief 获取K线数据（尚未实现）
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] period 周期，如m1/m5/d1
	 * \param[in] count 数量
	 * \return K线数据切片对象指针
	 */
	virtual WTSKlineSlice*	stra_get_bars(const char* stdCode, const char* period, uint32_t count) = 0;

	/*!
	 * \brief 获取Tick数据（尚未实现）
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] count 数量
	 * \return Tick数据切片对象指针
	 */
	virtual WTSTickSlice*	stra_get_ticks(const char* stdCode, uint32_t count) = 0;

	/*!
	 * \brief 获取委托明细数据（尚未实现）
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] count 数量
	 * \return 委托明细数据切片对象指针
	 */
	virtual WTSOrdDtlSlice*	stra_get_order_detail(const char* stdCode, uint32_t count) = 0;

	/*!
	 * \brief 获取委托队列数据（尚未实现）
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] count 数量
	 * \return 委托队列数据切片对象指针
	 */
	virtual WTSOrdQueSlice*	stra_get_order_queue(const char* stdCode, uint32_t count) = 0;

	/*!
	 * \brief 获取逐笔成交数据（尚未实现）
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] count 数量
	 * \return 成交数据切片对象指针
	 */
	virtual WTSTransSlice*	stra_get_transaction(const char* stdCode, uint32_t count) = 0;

	/*!
	 * \brief 获取最后一个Tick
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \return 最新的Tick数据对象指针
	 */
	virtual WTSTickData*	stra_get_last_tick(const char* stdCode) = 0;

	/*!
	 * \brief 获取持仓
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \param[in] bOnlyValid 获取有效持仓
	 * \param[in] iFlag 获取标记：1-多头，2-空头，3-净头寸
	 * \return 持仓数量，正数表示多头，负数表示空头
	 */
	virtual double stra_get_position(const char* stdCode, bool bOnlyValid = false, int32_t iFlag = 3) = 0;

	/*!
	 * \brief 枚举持仓，将通过on_position回调输出
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000，如果为空，则枚举全部
	 * \return 总持仓数量
	 *	
	 * \details 遍历当前所有持仓，通过回调函数返回每个持仓的信息
	 */
	virtual double stra_enum_position(const char* stdCode) = 0;

	/*!
	 * \brief 获取最新价格
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \return 最新价格，如果没有数据则返回0
	 */
	virtual double stra_get_price(const char* stdCode) = 0;

	/*!
	 * \brief 获取未完成订单数量
	 * \param[in] stdCode 标准化合约代码，格式如SSE.600000
	 * \return 未完成的订单数量（净值），正数为净买入，负数为净卖出
	 * 
	 * \details 返回指定合约的未完成订单统计：
	 *          - 用于风险控制和仓位管理
	 *          - UFT策略中特别重要的风控指标
	 */
	virtual double stra_get_undone(const char* stdCode) = 0;

	/*!
	 * \brief 订阅接口
	 */
	
	/*!
	 * \brief 订阅Tick数据
	 * \param[in] stdCode 标准化合约代码
	 * 
	 * \details 订阅指定合约的Tick数据推送，这是UFT策略的基础数据源
	 */
	virtual void stra_sub_ticks(const char* stdCode) = 0;
	
	/*!
	 * \brief 订阅委托队列数据
	 * \param[in] stdCode 标准化合约代码
	 * 
	 * \details 订阅指定合约的委托队列数据，用于分析市场深度
	 */
	virtual void stra_sub_order_queues(const char* stdCode) = 0;
	
	/*!
	 * \brief 订阅委托明细数据
	 * \param[in] stdCode 标准化合约代码
	 * 
	 * \details 订阅指定合约的委托明细数据，用于微观结构分析
	 */
	virtual void stra_sub_order_details(const char* stdCode) = 0;
	
	/*!
	 * \brief 订阅成交数据
	 * \param[in] stdCode 标准化合约代码
	 * 
	 * \details 订阅指定合约的逐笔成交数据，用于分析实际成交情况
	 */
	virtual void stra_sub_transactions(const char* stdCode) = 0;

	/*!
	 * \brief 日志接口
	 */
	
	/*!
	 * \brief 输出信息日志
	 * \param[in] message 日志信息
	 */
	virtual void stra_log_info(const char* message) = 0;
	
	/*!
	 * \brief 输出调试日志
	 * \param[in] message 日志信息
	 */
	virtual void stra_log_debug(const char* message) = 0;
	
	/*!
	 * \brief 输出错误日志
	 * \param[in] message 日志信息
	 */
	virtual void stra_log_error(const char* message) = 0;

protected:
	std::string _name;	///< 策略名称
};

NS_WTP_END